tsNetUploadSync
Type
function
Summary
Send a synchronous upload request to a server.
Syntax
tsNetUploadSync(<pURL>, <xHeaders>, <pData>, <rOutHeaders>, <rResult>, <rBytes>, [<pSettings>])
Description
The settings array can consist of the following elements (not all of the settings make sense for every possible transfer type):
"byte_range": Specify the range of data to be downloaded. This can be in the format of "X-Y", "X-", "-Y" or "X-Y,N-M" where X, Y, N and M and byte indexes. Some HTTP servers may ignore this request.
"cookie_file": Specify a filename to load cookies from. If this setting is present, the internal cookie engine will be enabled and the cookies stored in the file loaded into the engine.
"cookie_jar": Specify a filename to write all known cookies to. If this setting is present, the internal cookie engine of tsNet will be enabled. Note that this file will only be written to at unspecified times. Use the "cookie_list" setting below to force the file to be updated.
"cookie_list": Set this to a list of cookies (one per line) in Netscape / Mozilla format or regular HTTP (Set-Cookie:) style format to add to the internal cookie engine. There are also several strings that when passed to this setting will perform additional actions. Passing in the string "ALL" will erase all cookies held in memory. "SESS" will erase all session cookies in memory. "FLUSH" will write all cookies stored in memory to the file specified by the "cookie_jar" setting. "RELOAD" will reload all cookies from file specified by "cookie_file".
"cookies": The contents of this setting will be used to set a cookie in a HTTP request. It should be in the format of COOKIE_NAME=COOKIE_CONTENTS. Specify multiple cookies by separating them with a semi-colon. This setting does not enable the internal cookie engine of tsNet.
"disable_eprt": Set this option to true to stop tsNet from using the EPRT command when performing active FTP transfers.
"disable_epsv": Set this option to true to stop tsNet from using the EPSV command when performing passive FTP transfers.
"dont_modify_path": Set this option to true to stop tsNet from squashing "/../" and "/./" components from the URL path. RFC 3986 specifies that these should be removed.
"enable_tcp_keepalive": Set this option to true to tell tsNet to send TCP keepalive probes.
"expect100_timeout": Specify the number of milliseconds to wait for a response with a HTTP 100 (Continue) or HTTP 417 (Expectation Failed) status after setting a HTTP request containing an Expect: 100-continue header. The default is 1000ms.
"fail_on_http_error": Set to true to specify that HTTP status codes greater than 400 should be considered an error.
"force_basic_auth": Set to true to force HTTP basic authentication rather than allow tsNet to detect what authentication methods are supported by the server.
"force_digest_auth": Set to true to force HTTP digest authentication rather than allow tsNet to detect what authentication methods are supported by the server.
"ftp_filemethod": Set this to "nocwd" or "singlecwd" to change the method used by FTP to reach a particular file. Using "nocwd" will ensure all FTP commands use the full path to the file on the server. Using "singlecwd" will make tsNet issue a single CWD command to change to the directory that the file resides in before performing any other action on the file. The default is to issue a CWD command for each path part in the URL prior to performing any other action on the file in accordance with RFC 1738.
"ftp_ssl_ccc": Set this to "passive" or "active" to disable the SSL/TLS encryption after authenticating with the FTP server. All further communication on the command channel with the FTP server will be unencrypted. Use "passive" to only disable the encryption after the server requests it. Setting this to "active" will initiate the encryption shutdown.
"ftp_user_alt": Specify an alternate string to use for authentication if the standard FTP username and password negotiation fails.
"if_mod_since": If the last modified time (in seconds since 1 Jan 1970) of the file is later than this, then download the file.
"if_unmod_since": If the last modified time (in seconds since 1 Jan 1970) of the file is earlier than this, then download the file.
"ignore_content_length": Set this option to true to ignore the content length specified in HTTP or FTP transfers. tsNet will complete the download when the server ends the connection.
"interface": Specify the interface, IP address or host name to be used for the outgoing connection.
"junk_session_cookies": Set this option to true to tell tsNet to ignore all cookies loaded via the "cookie_file" setting that are session cookies.
"keepalive_idle": When "enable_tcp_keepalive" is set to true, use this setting to specify the number of second to wait while the connection is idle before sending keepalive probes. The default is 60 seconds.
"keepalive_interval": When "enable_tcp_keepalive" is set to true, use this setting to specify the number of seconds to wait between sending keepalive probes. The default is 60 seconds.
"local_port_range": Set the number of consecutive ports above the port specified by the "local_port_start" setting to try when finding an available port for a connection.
"local_port_start": Set the local port number of the socket to be used for the connection. It is recommended to also set "local_port_range" if you use this setting.
"max_file_size": Specify the maximum size of a file to download. If the file exceeds this value, the transfer will not start. This option has no affect is the file size is not known prior to the download.
"max_recv_speed": This option specifies the number of bytes per second to limit a download transfer to. Setting this to 0 disables any limiting.
"max_send_speed": This option specifies the number of bytes per second to limit an upload transfer to. Setting this to 0 disables any limiting.
"no_reuse": Set to true to specify that the connection to the server should be disconnected and not left open for any future connections.
"no_transfer": Set to true to connect to the server but not perform any transfer.
"password": Set to a string containing the password to be used in any authentication requests from the server.
"post_commands": (Business Edition only) Set to a list of raw FTP/SFTP commands (one per line) that should be executed on the server directly after any transfer.
"post_on_301": Set this option to true to tell tsNet to not convert POST requests to GET requests after a 301 response.
"post_on_302": Set this option to true to tell tsNet to not convert POST requests to GET requests after a 302 response.
"post_on_303": Set this option to true to tell tsNet to not convert POST requests to GET requests after a 303 response.
"pre_commands": (Business Edition only) Set to a list of raw FTP/SFTP commands (one per line) that should be executed on the server prior to any transfer.
"proxy_auth_basic": Set this option to true to force tsNet to use basic authentication when authenticating with a proxy server.
"proxy_auth_digest": Set this option to true to force tsNet to use digest authentication when authenticating with a proxy server.
"proxy_headers": Set to a list of headers (one per line) that should be sent to any proxy server that is being used.
"proxy_http_10": Set this option to true to tell tsNet to use HTTP/1.0 for any CONNECT tunnelling.
"referer": The contents of this setting will be used as the HTTP Referer:header sent as part of a HTTP request.
"resolve_hosts": Specify a list (one per line) of host to IP addresses to use when resolving host name for a request. Each line must be in the format of "HOSTNAME:PORT:ADDRESS".
"resume_from": Specify the number of bytes at which you want a transfer to start downloading or uploading.
"save_sent_headers": Set to true to specify that external should store a copy of all the headers that it sends to the server. This must be set to true to use the tsNetRetrSentHeaders function.
"skip_pasv_ip": Set this option to true to tell tsNet to ignore the IP address from the server’s 227 response message. tsNet will connect the data connection via the same IP address it used to set up the control connection.
"ssh_host_public_key": Set to the 128 bit MD5 checksum of the remote host's public key. The connection will be rejected unless they match.
"ssh_passphrase": (Business Edition only) Set to the passphrase for any included private key.
"ssh_private_key": (Business Edition only) Set to the private key file (including full system path) to be used in SFTP transfers.
"ssl_ciphers": Use this setting to specify a list of SSL ciphers (separated by colons) to be used when negotiating SSL connections.
“ssl_client_cert”: Specify the filename of a client SSL certificate to use for authentication to the server.
“ssl_client_cert_type”: Set to the format of the client SSL certificate. Supported formats are “PEM”, “DER” and “P12”.
“ssl_client_key”: Specify the filename of a SSL private key file that matches the client SSL certificate.
“ssl_client_key_pass”: Set to the password for the SSL private key.
“ssl_client_key_type”: Set to the format of the SSL private key. Supported formats are “PEM” and “DER”.
“ssl_proxy_client_cert”: Specify the filename of a proxy client SSL certificate to use for authentication to the HTTP proxy.
“ssl_proxy_client_cert_type”: Set to the format of the proxy client SSL certificate. Supported formats are “PEM”, “DER” and “P12”.
“ssl_proxy_client_key”: Specify the filename of a SSL private key file that matches the proxy client SSL certificate.
“ssl_proxy_client_key_pass”: Set to the password for the SSL private key.
“ssl_proxy_client_key_type”: Set to the format of the SSL private key. Supported formats are “PEM” and “DER”.
"trace": Set this option to true to tell tsNet to include all inbound and outbound data when using tsNetSetDebugCallback() rather than just header and informational data. When this option is set, a third parameter will be posted to the debug callback function specifying the type of data that is being passed to the callback function.
"transfer_encoding": Set this option to true to tell tsNet to request the response be sent in a compressed Transfer-Encoding (if the server supports it) that will be automatically uncompressed by tsNet when it is received.
"trust_location_auth": Set this option to true to tell tsNet to continue to send authentication details when following any HTTP redirects.
"try_ssl": Set this option to true to tell tsNet to try to connect via SSL. If the connection fails to establish via SSL, connect without using SSL.
"tunnel_http_proxy": Set this option to true to tell tsNet to tunnel all operations (all protocols) through the HTTP proxy.
"use_ascii_transfer": Set this option to true to tell tsNet to use ASCII mode for FTP transfers.
"use_pret": Set this option to true to tell tsNet to send a PRET command before sending PASV/EPSV when performing passive FTP transfers.
"user_agent": The contents of this setting will be used as the HTTP User-Agent: header sent as part of a HTTP request.
"username": Set to a string containing the username to be used in any authentication requests from the server.
"use_ssl": Set to true to connect using Transport Layer Security (TLS) for SMTPS and FTPS (explicit) connections.
"use_ssl_control": Set this option to true to ensure all control communication is encrypted.
Parameters
| Name | Type | Description |
|---|---|---|
pURL | The URL formatted as 'scheme://host:port/path' and URL-encoded as outlined in RFC 3986. The following schemes are supported: 'tftp', 'ftp', 'ftps', 'http', 'https' and 'sftp'. For SFTP connections, the path is not relative to the user's home directory, but must be the full system path. | |
xHeaders | For HTTP(s) connections, the headers to be sent to the server. For all other protocols, leave this blank. The contents of this variable will be replaced when the function returns with the headers that were sent to the server if the "save_sent_headers" array setting is specified below. | |
pData | The data that is to be sent to the server. | |
rOutHeaders | This variable will contain the headers that were returned from the server on completion. | |
rResult | This variable will contain the status code sent by the server to the last command that was issued during the transfer. For SFTP connections, this will always be 0. On error, the return value will be a string containing the error starting with "tsneterr:". | |
rBytes | This variable will contain the number of bytes that were downloaded during the connection. | |
pSettings | An array of additional settings that control how the transfer is initiated. |
Examples
local tHeaders, tResult, tBytes, tRecvHeaders, tData, tOutputData
put specialFolderPath("documents") & "/file.dat" into tFilePath
put URL("file:" & tFilePath) into tData
put tsNetUploadSync("ftp://user:pass@ftp.example.com/dir/file.dat", \
tHeaders, tData, tRecvHeaders, tResult, tBytes) into tOutputData
Related
function: tsNetRetrError, tsNetRetrSentHeaders
library: tsNet
Compatibility and Support
Introduced
LiveCode 8.1
OS
mac
windows
linux
ios
android
Platforms
desktop
server
mobile